Chapter 5: Configuration Commands

 The Configuration window allows the user to edit the settings of a file with a simple text editor built right into the program. The editor is not designed to become the world’s leading text editor. It does have things like Undo and uses the extra keys of the Macintosh extended keyboard like forward delete, home, end, page up, and page down. Nothing fancy like macros.

The configuration window is made up of two types of lines.  1- Command lines contain a command followed by its parameters. 2- Comment lines begin with a ‘#’ character and can contain anything you like following the comment symbol.  Comment lines are for notes to yourself.

The syntax of the commands are given with the various options shown. Each parameter is enclosed in <> characters. If alternatives for a parameter are possible they are listed separated by a vertical bar | character. A list which is separated by a | character means that you pick one of the items in the list. Here’s an example:

    LOGTYPE <GopherSurfer | MacHTTP | WebStar>

You can think of the | character as an OR. So, you could read this as LOGTYPE GopherSurfer or MacHTTP or WebStar. Here are the three possibilities you could enter for this command:

    LOGTYPE GOPHERSURFER
    LOGTYPE MACHTTP
    LOGTYPE WEBSTAR

Command names and parameters are NOT case sensitive. So, you could enter:

    LogType WebStar  or
    logtype webstar

with the same results. A command may also have optional parameters which depend on a setting from an “or” list. If this is the case, the parameter will be enclosed in [ ]’s for the syntax display. The times when they are used will be explained within the command description.

As you make changes in the Configuration window you have options that allow ServerStat to read the new settings into memory or you can save those settings for the program to read the next time it loads. If you open a settings file, ServerStat will automatically read in the values from that Configuration text. If you open the application, ServerStat will look for a file named “ServerStat.settings” in the same directory as the application to load. If it doesn’t find the file, it creates one with the initial settings that came with ServerStat. ServerStat Lite follows the same process except the file it looks for is “ServerStat Lite.settings.”

 Note: If you ever want to restore the initial settings that came with ServerStat you can rename the settings file or delete the default settings file name listed above. ServerStat or ServerStat Lite will create a new file the next time you run the program.

 The configuration commands are listed below in alphabetical order for easy reference.

AUTOQUIT
AUTOQUIT <On | Off>

This command allows the user to tell ServerStat to automatically quit the program after processing a log file. This command is designed for those who wish to have ServerStat run with a utility like Cron (you can download a copy of Cron at the following URL http://gargravarr.cc.utexas.edu/cron/cron.html) or those who want to write an AppleScript to launch a settings file at a particular time of day or day of the week. You can also set this option in the Additional Parameters dialog box available from the ServerStat menu.

 Note: ServerStat supports the core AppleEvents which allow you to open a settings file or quit the program.

 AUTORUN
AUTORUN <On | Off>

This command allows users to tell ServerStat to automatically begin processing the log file(s) specified in the Configuration text. ServerStat will flash a message for about 2 seconds when the program is executed letting you know that it read an AutoRun situation. To make changes in your settings with this option enabled, you need to press âŒ˜-. which will disable the AutoRun for the session and will allow you to make changes in your settings. You can also set this option in the Additional Parameters dialog box available from the ServerStat menu.

DATES
DATES <All | Relative | Start | End> [days | date]

This command allows you to specify what dates you would like the report to cover. You can specify that you would like to have all dates in the log reports, a number of days prior to the present day, or a start and end date. The All parameter is fairly straight forward. If you specify this command there is no extra parameters to specify. It looks like this:
    DATES All

You can get a report for the last week’s worth of activity using the Relative setting. When you specify Relative, you must add the number of days from the present you want to report for. So, for the last week enter:
    DATES Relative 7

You can get a report for any two start and end dates. For example, if you wanted a report for December 1994, you would use the DATES command twice to specify a start and end date like this:
    DATES Start 12/1/94
    DATES End 12/31/94

DEBUG
DEBUG <On | Off>

When the messages feature is turned on, you can use this option to see where you are in the log file as it is being processed. With DeBug on, each one-hundreth line processed will be displayed in the Message Window. Basically, this command is for those who like to tweak their log files with other applications like a spreadsheet program or utilities they have written for themselves. If a line in the log file is causing problems, this will help you locate it (within 100 lines) which is much easier to find than several thousand lines of a log. If the message feature is turned off, this option has no effect. You can also set this option in the Additional Parameters dialog box available from the ServerStat menu.

DNSLOOKUP
DNSLOOKUP <On | Off>

This feature allows you to set your server for maximum efficiency by having it record IP addresses rather than resolving user connections to domain names. If you turn this setting on, ServerStat will resolve the numerical IP addresses found in the log file using your domain name server. You must be connected to a network, and you must be running MacTCP and have it configured properly for DNS lookups to use this option. A SLIP connection will work with this feature. The default option is off because it does take considerably longer to process a file looking up all of the IP addresses. You can also set this option using the popup menu on the main ServerStat screen.

DOMAIN
DOMAIN <code> <name>

This command allows you to specify the translation values used by ServerStat when creating the [DOMAIN] section of a report (see Chapter 6 for information on the [DOMAIN] keyword). The code parameter is the last part of a domain name (i.e. edu, com, net, etc.). You can specify multiple levels if you like for example edu.ohio-state. There is no interface equivalent to this command. You must enter these in the Configuration window. A fairly comprehensive list of DOMAIN entries is provided as part of the default settings. The Name parameter is the text you would like to have the code converted to for the report. For example, if you wanted all of the “edu.ohio-state” addresses to convert to the [DOMAIN] line of “The Ohio State University” you should enter the line:

    DOMAIN edu.ohio-state "The Ohio State University"

The codes should be entered in their reverse name order. The domain names are reversed in order to make them sort in groups more efficiently.

 Note: The codes are searched in the order they appear in the Configuration window. So, you may need to specifically place the more complete names ahead of the shorter names to allow ServerStat to see your code. For example, “edu.ohio-state” should appear before “edu.”

EXCLUDE
EXCLUDE <address>
(See also the INCLUDE command)

This command allows you to specify a particular machine or group of machines which you do not want to appear in the report. The default settings do not include any EXCLUDE commands. If you would like to create a server access report that does not count your accesses, for example, you might enter an exclude command that looks like this:

    EXCLUDE 128.146.252.130 (<-- replace this address with your machine’s address)

You could also exclude an entire group of machines using a wildcard character like:

    EXCLUDE 128.146*

which would exclude all IP addresses which begin with that prefix. You can also exclude machines based on their resolved domain name. For example, if you would like to exclude all of the machines at the University of Michigan (something many Ohio State people might like to do… a little Big Ten humor there) you could enter:

    EXCLUDE "edu.umich*"

ServerStat will allow you to enter multiple EXCLUDE commands. ServerStat Lite will only accept one EXCLUDE command.

 Note: You cannot use the EXCLUDE IP address format if your log file already contains domain names (i.e. you will have told your server program to look up domain names as accesses occur). If you know the IP address of a machine that you want to exclude, that is faster than excluding by domain name. If you exclude by address, it isn’t uncommon to see IP addresses being resolved in the Message window which don’t end up in your report. This is because ServerStat doesn’t know from the IP address the name of the machine until it looks it up. That’s why excluding by IP address is faster.

 FASTMODE
FASTMODE <On | Off>

This command lets you decide how ServerStat should act with other programs. If you want ServerStat to process a log file as quickly as possible and tie up the computer until it is finished, you can turn this option on. If you want ServerStat to run in the background or you want to work on other programs while a report is being generated, this setting should be turned off. You should only turn this option on if you are willing to let the computer run until the log is finished. You cannot stop the log file processing once you start with this option turned On.

FILTER
FILTER <In | Out> <filter parameter>

This command is designed to let the user have control over what files are processed in the report. Basically, this command was designed for web servers. Since there are so many graphics files associated with a single page this option was created to give a more accurate count of accesses. For example, users may wish to filter out all of the files which end in .gif. They may only want to report based on a single directory so they would want to filter those items into the report.

The first parameter tells ServerStat whether or not you want to filter the item In or Out of the report. An item must pass the Filter In test before the Filter Out option is considered. So, using a command like Filter In "*.html" would automatically filter out all files that don’t end in .html.

The second parameter tells ServerStat which specifications you want filtered in or out. The filter parameter uses a wildcard character to allow you to specify a prefix or a suffix which is to be matched. You can only use one wildcard character in a filter parameter. The filter function happens just after a line of the log is separated into its various parts. So, you should use “:” characters for directory separators. Here are a few examples:
    Filter In "*.html"    would allow items that end in .html
    Filter Out "*gif"     would eliminate all graphics files ending in .gif
    Filter In ":Client1*" would allow items that began with this prefix

There is no menu item or dialog box associated with this feature. It requires entry of information into the Configuration window. Fortunately, Macs where designed to have a keyboard for just such occasions.

 Note: GopherSurfer logs report the complete pathname and do not begin with a “:” character when reporting file names. MacHTTP and WebStar logs begin with the published directory represented as a single “:” so the filter parameter which specifies a prefix should be aware of what the log format is.

 Note: ServerStat Lite allows one Filter In and one Filter Out command to be entered. ServerStat allows multiple command lines of each.

 FORMAT
FORMAT <HTML | TEXT>

This command allows you to specify which type of report output you would like ServerStat to create. You should only have one FORMAT command in the configuration text. If more than one is in the text the last one found will be used. This is the same as selecting the radio buttons next to Output: on the main ServerStat window.

INCLUDE
INCLUDE <address>
(See also the EXCLUDE command)

This command allows you to specify a particular machine or group of machines which you want to appear in the report. The default settings do not contain any include commands which means that by default all machines will be included in the report. If, for example, you would like to create a report which only contains a single users access you could specify by IP address or domain name the machine you would like to include. The format for the command is the same as the EXCLUDE command listed above. There is no menu command or dialog box associated with the INCLUDE command. You must enter these values into the Configuration Window. Remember to select Scan Config from the ServerStat menu to allow ServerStat to read your new values into memory.

 Note: The fastest method for using this command is to set your server not to translate IP addresses into domain names and then specify the INCLUDE command using the IP address of the machine you would like to include.

 Note: ServerStat Lite will only allow one INCLUDE command. ServerStat will allow you to have multiple INCLUDE commands for greater flexibility.

 LOG
LOG <filename>

This command is used to specify the log filename or pathname you wish for ServerStat  to generate a report for. Full pathnames are permitted with this command and allow for the least chance for errors. Since the MacOS will sometimes set the working directory for an application it may not be consistent. So, when auto generating a configuration window, ServerStat will always list the complete pathname to the file you requested either in the Configuration window or with the Log File button. Using this option is equivalent to selecting the Log File button on the main ServerStat window. You must specify a LOG command in the Configuration window to use the AUTORUN feature. Here’s an example command:
    LOG "Server:Servers:WebStar:WebStar.log"

 Note: If your pathname or filename contains spaces, you must enclose the pathname inside quotation marks.

 Note: ServerStat Lite only allows processing on a single log file per report. ServerStat allows you to process batches of log files by entering multiple LOG commands.

  LOGTYPE
LOGTYPE <GopherSurfer | MacHTTP | WebStar>

This command lets ServerStat know what type of log you are going to process. You should only enter one LOGTYPE command in the Configuration window. This command is the same as selecting the option from the Log Type popup menu on the ServerStat main window.

 Note: Remember, if you are processing a WebStar log file and have used the WebStar Admin program to change the format of the log from the default you need to let ServerStat know what the format of the log is. See the PATTERN command or the Log Format… menu option for information on doing this.

 MESSAGES
MESSAGES <On | Off>

This command lets you turn on or off the message feature. When messages are turned on, the program will display messages to you in the Message window as it processes the file. For example, if you have ServerStat looking up domain names for IP addresses, it will display them in the message window. This option is the same as selecting the popup menu option Messages: on the ServerStat main window.

OUTPUT
OUTPUT <filename>

This command is used to specify the output filename or pathname you for ServerStat to write the generated report to. Full pathnames are permitted with this command and allow for the least chance for errors. Since the MacOS will sometimes set the working directory for an application it may not always be what is expected. So, when auto generating a configuration window, ServerStat will automatically specify a full pathname. You must specify an OUTPUT command in the Configuration window to use the AUTORUN feature. Here’s an example command:
    OUTPUT "Server:Servers:ServerStat:ServerStat Report"

PATTERN
PATTERN <token token ... token>

WebStar introduced the ability to specify what is recorded in the servers log file and in what order the tokens appear. The PATTERN command is used to tell ServerStat what appears in the log file and in what order they appear. Entering the tokens is not case sensitive. If you do not specify a pattern command, a WebStar log will be processed with the WebStar default log file format which is the same as a MacHTTP log file. You can also specify the format of the log file by selecting the Log Format… command from the ServerStat menu. The available tokens are the same as they appear in the WebStar Admin program:

DATE          entered in the format MM/DD/YY
TIME          entered in 24HR time HH:MM:SS
RESULT        status of the transmission OK, ERR!, or PRIV
HOSTNAME      IP address or name of the client’s machine
URL           the file the client requested
BYTES_SENT    the number of bytes in the transmission to the client
AGENT         the type of browser the client was using
PATH_ARGS     these are currently ignored for statistics
SEARCH_ARGS   these are currently ignored for statistics
REFERER       the URL of page where the client came from to your server
USER          the authenticated username (if turned on in WebStar)
FROM          usually the user e-mail address
TRANSFER_TIME the amount of ticks the transmission took. ServerStat automatically
              converts this amount to HH:MM:SS.SS - down to the 1/100th second.

Here’s an example PATTERN command:

    PATTERN Date Time Result HostName URL Bytes_Sent Agent

 Note: Because MacHTTP and WebStar logs are very similar you can use the WebStar setting on a MacHTTP log. This has the added advantage of being able to remove byte counts from your report if you would rather they weren’t there. Just eliminate all of the tokens from the end of the PATTERN command that you do not wish to have reported. Modifying the above PATTERN command would be:
    PATTERN Date Time Result HostName URL

You can remove ONLY from the end, not in the middle.

 PREFIX
PREFIX <pathname>

This command allows you to specify a prefix of all filenames which will be truncated down to a single vertical bar ‘|’ character. The command was designed for GopherSurfer logs which record the entire pathname to a file. Eliminating the prefix increases server security as well as makes the reports more readable. Here is an example PREFIX command:
    PREFIX "Server:Servers:Gopher:Published:"

 Note: If your prefix contains spaces, you should enclose the prefix in quotation marks.

SUBLEVELS (commercial version only)
SUBLEVELS <0 | 1 | 2 | 3 | 4 | 5>

For the [SUBDOMAIN] section of the report, ServerStat Lite reports each individual machine as a separate line of the report. ServerStat gives more flexibility with this section of the report. SUBLEVELS allows you to specify the number of significant levels to include in this section of the report. Suppose you wanted to include a report of just the domain and one additional level. You could enter the command:
    SUBLEVELS 2

which would write a report including the following subdomain listings:
    edu.ohio-state
    com.netscape
    edu.uiuc

specifying this setting would automatically group all machines together which fall into a certain cluster. If you specify a setting of 0, then each machine will appear on its own line which is the same as ServerStat Lite.